Release 10.1A: OpenEdge Development:
Web Services

Documenting client programming requirements

Most Web services built with OpenEdge require client programmer documentation along with the WSDL file in order to use the Web service interface. This information describes any special requirements for Web service operation parameters and other requirements for Web service binding and programming. The requirements for most input and output parameters and their data types are based on standards supported in the WSDL file and that most Web service client toolkits support without additional programming. However, there are some unique features of OpenEdge support for building Web services that might be helpful or necessary for client programmers to know in order to be successful:

Open Client object model — The Open Client object model supports certain built-in object management methods whose availability and use depends on the session model of the Web service application and the particular type of Open Client object in use. For example, in a session-managed application, the instantiation of each object returns a unique ID that identifies that object and must be maintained and supplied in all method calls on that object. In general, the client programmer needs to understand when they can and should use these built-in methods on an object and how to use them.
SOAP format — All Web service client platforms support a limited choice of SOAP formats, often fewer than the three supported by OpenEdge. The client programmer needs to know the SOAP format that a particular Web service uses in order to know whether their client platform supports it. This information is certainly available in the WSDL, but it might be helpful to know before downloading the WSDL. Also, you might provide versions of the Web service for each supported SOAP format and identify them accordingly.
Relational data — OpenEdge allows you to build Web services that pass arrays of complex data types as input and output parameters, thus supporting the exchange of relational data (sometimes known as data sets, result sets, data objects, or as in Progress temp-tables). For many 4GL-built Web services, the WSDL supplies all the schema information required to access these relational data, particularly for static temp-tables. However, for Web services that pass dynamic temp-tables, where the schema is not defined at compile-time, the client programmer needs additional documentation on the schema required to pass dynamic temp-tables as input parameters.
SOAP faults — The client programmer needs to understand the format of error messages that are returned from 4GL-built Web services.

For more information on all these requirements (and more) for programming client applications to access Progress 4GL Web services, see Part II, "Clients Accessing Progress 4GL Web Services."